Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Convert issue templates in markdown to GitHub's issue forms #1562

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Convert issue templates in markdown to GitHub's issue forms #1562

wants to merge 5 commits into from

Conversation

mitchelbaker-cisa
Copy link
Collaborator

@mitchelbaker-cisa mitchelbaker-cisa commented Feb 11, 2025 •
edited
Loading

🗣 Description

Converts markdown versions of "new idea" and "bug report" templates to Github's issue forms.

GitHub documentation if interested.

💭 Motivation and context

This issue would be useful because issue forms encourage specific, structured information we want included in issues, as well as required fields/input validation.

Closes #1283

🧪 Testing

Check out 3-newidea-scubagear.yaml and 4-bugreport-scubagear.yaml files for formatting/consistency (copied the same files into a personal repository to test since these files have to be committed to a main branch).

Please comment in this PR for any new inputs we want added to either the new issue or bug report templates.

✅ Pre-approval checklist

  • This PR has an informative and human-readable title.
  • PR targets the correct parent branch (e.g., main or release-name) for merge.
  • Changes are limited to a single goal - eschew scope creep!
  • Changes are sized such that they do not touch excessive number of files.
  • All future TODOs are captured in issues, which are referenced in code comments.
  • These code changes follow the ScubaGear content style guide.
  • Related issues these changes resolve are linked preferably via closing keywords.
  • All relevant type-of-change labels added.
  • All relevant project fields are set.
  • All relevant repo and/or project documentation updated to reflect these changes.
    - [ ] Unit tests added/updated to cover PowerShell and Rego changes.
    - [ ] Functional tests added/updated to cover PowerShell and Rego changes.
    - [ ] All relevant functional tests passed.
  • All automated checks (e.g., linting, static analysis, unit/smoke tests) passed.

✅ Pre-merge checklist

  • PR passed smoke test check.

  • Feature branch has been rebased against changes from parent branch, as needed

    Use Rebase branch button below or use this reference to rebase from the command line.

  • Resolved all merge conflicts on branch

  • Notified merge coordinator that PR is ready for merge via comment mention

  • Demonstrate changes to the team for questions and comments.
    (Note: Only required for issues of size Medium or larger)

✅ Post-merge checklist

  • Feature branch deleted after merge to clean up repository.
  • Verified that all checks pass on parent branch (e.g., main or release-name) after merge.

@mitchelbaker-cisa mitchelbaker-cisa added the enhancement This issue or pull request will add new or improve existing functionality label Feb 11, 2025
@mitchelbaker-cisa mitchelbaker-cisa added this to the Marlin milestone Feb 11, 2025
@mitchelbaker-cisa mitchelbaker-cisa self-assigned this Feb 11, 2025
@tkol2022
Copy link
Collaborator

Recommended changes to Bug Report template

  • Add a ScubaGear version field
  • I recommend combining screenshots and steps to reproduce. I have always wondered why those are separate.

@tkol2022
Copy link
Collaborator

Recommended changes to Feature Request template

  • I never understood why implementation notes and acceptance criteria are separate. My opinion would be to move the checkboxes from acceptance criteria to implementation notes and drop the acceptance criteria section.

@tkol2022
Copy link
Collaborator

@mitchelbaker-cisa As I was reviewing this PR I couldn't help but think that there is a related issue out there. Should we incorporate the scope of that issue into this PR as well and get rid of two birds with a single stone?

Here is a proposal. Decide as you will. I don't have any strong feelings on it.

  • Do a review of all the bugs reported in the past
  • Use that information to augment whatever information we ask from the user on the YAML forms that you created

@mitchelbaker-cisa
Copy link
Collaborator Author

@tkol2022 Agreed I think its a good idea to include #243 since its similar scope. Will plan to review previous troubleshooting/bug reports to determine what data was commonly requested and then what PowerShell commands are used to collect this information.

@mitchelbaker-cisa
Copy link
Collaborator Author

Recommended changes to Feature Request template

* I never understood why implementation notes and acceptance criteria are separate. My opinion would be to move the checkboxes from acceptance criteria to implementation notes and drop the acceptance criteria section.

Issue forms are in public preview/beta and they're not yet supported for pull request templates. See last paragraph in GitHub's documentation.

For this PR, we can still combine the two sections per your recommendation in pull_request_template.md. Then the switch to a pull request form template would come in a follow-up issue.

@schrolla
Copy link
Collaborator

Recommended changes to Feature Request template

  • I never understood why implementation notes and acceptance criteria are separate. My opinion would be to move the checkboxes from acceptance criteria to implementation notes and drop the acceptance criteria section.

Hard disagree. These are completely separate things, suggest they remain so. Implementation steps are the "what steps do we need to take" and acceptance criteria is "how do we know when its done". They are often different in that its possible to take all the implementation steps and NOT meet the acceptance criteria. Often because the criteria have "extra steps" that aren't fully documented in implementation because they are ancillary, such as documenting outcomes.

schrolla
schrolla requested changes Feb 14, 2025
View reviewed changes
Copy link
Collaborator

@schrolla schrolla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I codified the suggested version inclusion and added another suggestion for Initialize-SCuBA output to be included. The former is just to make inclusion easier, the latter is suggested but not required.
Everything else looked good as is. And I do recommend keeping implementation notes and acceptance criteria separate as the focus of each is different.

.github/ISSUE_TEMPLATE/2-bugreport.yaml
Comment on lines +29 to +30
required: true
- type: textarea
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add ScubaGear version to bug report.

Suggested change
required: true
- type: textarea
required: true
- type: textarea
attributes:
label: "ScubaGear Version"
description: Please indicate the version of ScubaGear being run.
placeholder: Run Invoke-SCuBA -Version locally and paste output here to ensure correct version is indicated.
validations:
required: true
- type: textarea

.github/ISSUE_TEMPLATE/2-bugreport.yaml
label: Expected behavior
description: What did you expect to happen that didn't?
validations:
required: true
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest adding another optional field here to capture the output from Initialize-SCuBA. Doing so has the following value:

  1. This verifies it has been run and gets rid of issues around uninstalled or incorrect version installs of dependencies.
  2. Whether it installs anything new, it confirms the versions of each dependency in use, helping identify issues with bugged dependency module versions.
  3. It's easy to collect by users and is fairly general information. The only exception being it might identify their username in the OPA install path.
Suggested change
required: true
required: true
- type: textarea
attributes:
label: Output from Initialize-SCuBA
description: |
Paste the results here:
placeholder: "Tip: Run Initialize-SCuBA on the client where you are running ScubaGear and copy/paste the output here."
validations:
required: false

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@schrolla schrolla schrolla requested changes

@tkol2022 tkol2022 Awaiting requested review from tkol2022

Requested changes must be addressed to merge this pull request.

Assignees

@mitchelbaker-cisa mitchelbaker-cisa

Labels
enhancement This issue or pull request will add new or improve existing functionality
Projects
None yet
Milestone
Marlin
Development

Successfully merging this pull request may close these issues.

Convert issue templates in markdown to Github's issue forms
3 participants
@mitchelbaker-cisa @tkol2022 @schrolla